\documentclass[12pt,a4paper]{article}
\usepackage{times,url,hyperref}
\baselineskip = 6mm
\parskip = 2mm
\parindent = 1cm


\textheight 9.550in
\textwidth 7.00in
\oddsidemargin -0.245in
\headsep -0.60in

\title{pysbml documentation, Version 0.2}
\author{{Colin S. Gillespie}\\
School of Mathematics and Statistics\\
University of Newcastle upon Tyne, UK\\
email: \href{mailto:c.gillespie@ncl.ac.uk}{\texttt{c.gillespie@ncl.ac.uk}}}
\date{\today}

\begin{document}
\sf
\maketitle

\tableofcontents

\newpage

\section{Introduction}

\subsection{Overview}

Pysbml is \href{http://www.python.org}{Python} library which provides tools for the SBML community. It is intended that the functionality provided by this module be incorporated within another tool. For example, the \href{http://www.basis.ncl.ac.uk}{BASIS project} uses pysbml for model visualisation and simulation.

\subsection{Requirements}

To install the pysbml a number of modules are required:
\begin{itemize}
\item \texttt{libSBML} with the python bindings enabled \\ \href{http://www.sbml.org/libsbml.html}{\url{www.sbml.org/libsbml.html}}
\item \texttt{gillespie2.py}$^*$ - \href{http://www.basis.ncl.ac.uk/software.html}{\url{www.basis.ncl.ac.uk/software}}
\item \texttt{pydot.py}$^*$ - \href{http://dkbza.org/pydot.html}{\url{dkbza.org/pydot.html}}
\item Graphviz$^*$ - \href{http://www.graphviz.org/}{\url{www.graphviz.org}}
\item \texttt{libxml2}$^*$ and \texttt{libxslt}$^*$ - fairly standard python modules
\item \texttt{ZSI}$^*$ - \href{http://pywebsvcs.sourceforge.net/}{\url{pywebsvcs.sourceforge.net}}
\end{itemize}
Packages marked with $^*$ are not essential when installing pysbml. Instead, the full functionality of pysbml will not be available.

\subsection{Installing pysbml}

Pysbml can be installed in the standard method for python libraries, namely
{\small
\begin{verbatim}
	tar xvfz pysbml.tar.gz
	cd pysbml
	python setup.py install
\end{verbatim}}
\noindent The style-sheets accompanying the package are placed into
{\small
\begin{verbatim} 
/usr/xml_schemas
\end{verbatim}}
\noindent If you installed the package in a non-standard place, i.e. you did not follow the setup procedure above, then you will have to alter the \texttt{path} attribute in \texttt{pysbml.py} to point to where the style-sheets are saved, i.e.
\begin{verbatim}
from pysbml import pysbml
pysbml().path = '/my_place/'
\end{verbatim}
This value is then stored in \texttt{~/.pysbml}.

\section{Introduction to pysbml}

As with all python modules, we first import pysbml to use it i.e.
\begin{verbatim}
from pysbml import pysbml
\end{verbatim}
Pysbml can read in a sbml string/file or a sbml-shorthand string/file
\begin{verbatim}
p = pysbml(sbml=None, sbml_file=None, mod=None, mod_file=None)
\end{verbatim}
If no arguments are passed to pysbml, then an empty sbml model is created. 

\subsection{Global variables}

There are a number of global attributes which are accessible by all classes within pysbml. These attributes, sbml, d (a libsbml document), model\_urn, simulation\_group\_urn, (basis) username/password, and path.

Basically, \texttt{pysbml().sbml} and \texttt{pysbml().method().sbml} point to the same thing.

\section{Model building}

Using pysbml it is possible to construct an SBML model from the command line. Currently, pysbml supports compartments, species, reactions, parameters, and events. Each supported SBML attribute has corresponding method calls of add, modify and delete, i.e. for species we have  \texttt{addSpecies},  \texttt{deleteSpecies} and \texttt{modifySpecies}.

\subsection{Creating or loading a model}

An empty level 2 SBML is created via
{\small
\begin{verbatim}
from pysbml import pysbml
p = pysbml().sbmlModel()
print p
\end{verbatim}}
\noindent Alternatively, an existing model can be loaded up from a file
{\small
\begin{verbatim}
p = pysbml(sbml_file = `LV2.xml').sbmlModel()
\end{verbatim}
where LV2.xml refers to a sbml file.

\subsection{Example of \texttt{add} method calls}

Elements can be added in any order. For example, we can create a reaction then create the species in the reaction.
{\small
\begin{verbatim}
p.addReactions(Id=`Conversion', 
    listOfReactants=[{`Species':`ATP'}],\
    listOfProducts=[{`Species':`ADP'}], \
    KineticLaw={`Formula':`a * ATP'})
p.addSpecies(Id=`ADP', Compartment=`Cell', InitialAmount=0)
p.addSpecies(Id=`ATP', Compartment=`Cell', InitialAmount=0)
p.addParameters(Id=`a', Value=1)
\end{verbatim}}

\subsection{Example of \texttt{modify} method calls}

Any elements in a SBML model can be modified. Furthermore, if an id is modified then any other part of the SBML model that refers to that model is altered, i.e. if a compartment id is changed, then this change also occurs in the species elements. The recursive flag disables this behaviour.
{\small
\begin{verbatim}
p.modifySpecies(ADP={'Id':'new_adp', 'InitialAmount':10})
p.modifySpecies(ATP={{'Id':'new_atp'}, recursive=0)
p.modifySpecies(X={{'Name':'Y'})
\end{verbatim}}

\subsection{Example of \texttt{delete} method calls}

Each delete method takes in a list of ids. Again, the recursive flag can be set. If the flag is set to 1 then all elements depending on the deleted are id are all deleted, i.e. if you delete a species, then all reactions and events are also deleted. If the recursive flag is set to 0, then only that element is deleted.
{\small
\begin{verbatim}
p.deleteCompartments(['Cell', 'inner_cell'], recursive=0)
p.deleteEvents(['E1'])
\end{verbatim}}

\subsection{Additional methods}

Other functions include 
\begin{itemize}
\item \texttt{validate()} - this calls the libSBML validator and outputs the results.
\item \texttt{addId(`id')} - adds an id to the model.
\item \texttt{addNotes(`some notes')} = adds some notes to the model.
\end{itemize}

\subsection{Relation to libsbml}

The libsbml document object can accessed through the attribute \texttt{d}: 
{\small
\begin{verbatim}
p = pysbml()
print p.sbmlModel().d.getModel()
\end{verbatim}}


\section{Visualisation}

Pysbml uses graphviz to create a network diagram of a pathway. Consequently, we can output the graphic in any format that graphviz supports. The common output formats are \textit{fig, gif, imap, cmapx, jpeg, png, ps, ps2, and wbmp}. For a fuller list please see the graphviz website.

There are three visualisation methods:
\begin{itemize}
\item \texttt{visualiseModel()} - is used to produce a diagram of the entire model.
\item \texttt{visualiseSpecie(specie\_num)} - is used to produce a diagram of all reactions interacting with a particular specie. The specie is identified by \texttt{specie\_num} which is a non-negative integer.
\item \texttt{visualiseReaction(reaction\_num)} - is used to produce a diagram of all species involved with a particular reaction. The reaction is identified by \texttt{reaction\_num} which is a non-negative integer.
\end{itemize}
The three visualisation methods return a \texttt{VisualiseFormats} class. This class has two (callable) methods:
\begin{itemize}
\item \texttt{static(format)} - this return the graphic in the format requested;
\item \texttt{web(format)} - this returns a graphic and a corresponding image map.
\end{itemize}
Some example calls:
{\small
\begin{verbatim}
from pysbml import pysbml
p = pysbml(sbml_file = 'LV2.xml')
model = p.visualiseModel().static('jpg')
specie = p.visualiseSpecie(1).static('ps')
reaction = p.visualiseReaction(2).static('png')

imagemap, graphic = p.visualiseModel().web('gif')
\end{verbatim}}

\section{sbml2html}

An example of changing an sbml model to a html is:
{\small
\begin{verbatim}
from pysbml import pysbml
p = pysbml(sbml_file = 'LV2.xml')
html = p.sbmltohtml()
\end{verbatim}}
\noindent The output can now be viewed by any standard web browser.

The style-sheets used in this transformation were written by Oliver Becker (see Links for his website).

\section{SBML shorthand}

SBML-shorthand is a language for describing systems biology models. It is designed primarily for translation (compilation) into SBML. It is not associated with any particular modelling or simulation tool. SBML itself is not intended to be read by humans or written  by hand -- SBML-shorthand is.

An example of SBML shorthand is:
{\small
\begin{verbatim}
from pysbml import pysbml
p = pysbml(sbml_file = `LV2.xml')
print p.sbml2mod()
\end{verbatim}}
\noindent This would produce
{\small
\begin{verbatim}
@model:2.1.2=Lotka_Voltera system
@compartments
 compartment=1.0
@species
 compartment:X=500.0
 compartment:Y=1000.0
@parameters
 a=0.25
 b=0.0025
 c=0.125
@reactions
@r=PreyProduction
 X -> 2Y
 a * X
@r=PredatorReproduction
 X+Y -> 2Y
 b * X * Y
@r=PredatorDecay
 Y -> 
 c * Y / (1 + Y)
\end{verbatim}}
\noindent For details of the current SBML-shorthand specification go to the website given in the Links. 

\section{Simulation}

Pysbml currently has an interface to the Gillespie algorithm, an exact stochastic simulator. An example is
{\small
\begin{verbatim}
p = pysbml(sbml_file = 'LV2.xml')
max_time, no_of_steps,seed = 1.5, 10, 12345
s = p.simulate()
g = s.gillespie(max_time, no_of_steps, seed)
print g.getData()
\end{verbatim}}

\section{BASIS Web-services}

pysbml provides a wrapper around the BASIS web-services. To access the web-services, first an account needs to be created on BASIS. Go to \href{https://www.basis.ncl.ac.uk/basis/}{\url{https://www.basis.ncl.ac.uk/basis/}} to create an account. Now to connect to BASIS we use the connectToBasis method:
{\small
\begin{verbatim}
e = pysbml()
c_to_b = p.connectToBasis(username='XXX', password='***')
#Check to see that we are logged on 
c_to_b.isLoggedIn() 
c_to_b.logOut()
#Check to see that we are logged out 
c_to_b.isLoggedIn() 
\end{verbatim}}
Note: after the first time you log, your username and password is stored in ~/.basis. This means you do not need to enter your username and password again.

\subsection{User Details}

To access your user details on BASIS, we simply call the user details method, e.g.
{\small
\begin{verbatim}
ud = pysbml().connectToBasis().userDetails()
\end{verbatim}}
This returns a python dictionary, and all the usual methods are available. We change the BASIS variables by simply changing the dictionary:
{\small
\begin{verbatim}
print ud
ud['fullName'] = 'Colin Gillespie'
\end{verbatim}}
Note: you can not change your username.

\subsection{Model Tables}

To view the models stored in BASIS we access the modelTable method, e.g.
{\small
\begin{verbatim}
md = pysbml().connectToBasis().modelTable()
\end{verbatim}
}
We can now view the private model table and the public model table, 
{\small
\begin{verbatim}
print md.getMyModelInfo(pretty_print=True)
print getPublicModelInfo(pretty_print=True)
\end{verbatim}
}
The argument \texttt{pretty\_print} is defaulted to \texttt{True}. Setting it equal to \texttt{False}  will return a list of lists.

\subsection{Models}

First, we access the model class
{\small
\begin{verbatim}
md = pysbml().connectToBasis().model()
\end{verbatim}
}
The variable md is dictionary with a few additional methods added. For example,
{\small
\begin{verbatim}
md['modelUrn'] = 'urn:basis.ncl:model:4'
print md
print md.sbml
\end{verbatim}
}
Note the model 'urn:basis.ncl:model:4' is a public model.

We can add a model to BASIS and alter it's details easily, e.g
{\small
\begin{verbatim}
c_to_b = pysbml(sbml_file='LV2.xml').connectToBasis()
md = c_to_b.model()
md.saveModel()
print md
md['modelName'] = 'My first model'
md['modelNotes'] = 'This is my first model'
\end{verbatim}
}
Other methods available are
{\small
\begin{verbatim}
#Delete the current model from basis
md.deleteModel()
#Copies the model from the public space into your private space for editing.
md.copyModel('urn:basis.ncl:model:4')
#View available simulation data for this model
md.getSimulationData()
\end{verbatim}
}

\subsection{Simulation}

The BASIS system uses a the gillespie stochastic simulator to run models. We access the simulator in the following manner:
{\small
\begin{verbatim}
c_to_b = pysbml(sbml_file='LV2.xml').connectToBasis()
#Must have a valid model_urn, if not then set the variable
#or add a model to BASIS
print c_to_b.model_urn
sim = c_to_b.simulate()
#Sets of a simulation
#no_of_sims = integer, range 1-1000
#no_if_iters = integer, how many data points do you wish to store.
sim.simulate(run_name, max_time, no_of_sims, no_of_iters)

print sim.simulation_group_urn
#Stops a simulation. Does not delete any data
sim.killSimulation()

#Stops and deletes any data
deleteSimulation()
\end{verbatim}
}
Obviously once you have ran a simulation, you will want to retrieve the data. There are a variety of services that enables us to do this
{\small
\begin{verbatim}
sim = pysbml().connectToBasis().simulate()
#Setting pretty_print =False, returns a list of lists
print sim.getSimulationData(pretty_print=True)
sim_urn = sim.getSimulationData(pretty_print=False)[0][0]
sim.simulation_group_urn = sim_urn
#View some details about the simulation
print sim.getSimDetails()
#Get the data and save it into the directory '/tmp/'
sim.getData(dir='/tmp/')
\end{verbatim}
}
Currently getting data from BASIS is a bit inefficient. This altered in the near future.


\section{Acknowledgements}

We thank Jo Mathews for discussions about the visualisation method.

\section{Links}

\begin{tabular}{rl}
Author's website & \href{http://www.mas.ncl.ac.uk/~ncsg3}{\url{www.mas.ncl.ac.uk/~ncsg3}} \\
BASIS & \href{http://www.basis.ncl.ac.uk/}{\url{basis.ncl.ac.uk}} \\
SBML & \href{http://sbml.org/}{\url{sbml.org}} \\
SBML Documents & \href{http://sbml.org/documents/}{\url{sbml.org/documents/}} \\
libSBML &
\href{http://www.sbml.org/libsbml.html}{\url{www.sbml.org/libsbml.html}}\\
SBML Shorthand &
\href{http://www.staff.ncl.ac.uk/d.j.wilkinson/software/sbml-sh/}{\url{www.staff.ncl.ac.uk/d.j.wilkinson/software/sbml-sh/}} \\
Python & \href{http://www.python.org/}{\url{www.python.org}}\\
Pydot module & \href{http://dkbza.org/pydot.html}{\url{dkbza.org/pydot.html}}\\
Graphviz & \href{http://www.graphviz.org/}{\url{www.graphviz.org}} \\
Oliver Becker & \href{http://www.informatik.hu-berlin.de/~obecker/}{\url{www.informatik.hu-berlin.de/~obecker/}} \\
ZSI module & \href{http://pywebsvcs.sourceforgp.net/}{\url{pywebsvcs.sourceforgp.net}}
\end{tabular}



\end{document}
